package com.rolerealm.service;

import com.rolerealm.domain.dto.CharacterCreateDTO;
import com.rolerealm.domain.dto.CharacterSearchDTO;
import com.rolerealm.domain.dto.CharacterUpdateDTO;
import com.rolerealm.domain.vo.CharacterDetailVO;
import com.rolerealm.domain.vo.CharacterVO;
import com.rolerealm.domain.vo.PageResult;
import com.rolerealm.domain.vo.PresetInitResult;

import java.util.List;

/**
 * 角色管理服务接口
 * 
 * @author RoleRealm Team
 * @version 1.0.0
 */
public interface CharacterService {

    /**
     * 分页查询角色列表
     * 
     * @param searchDTO 搜索条件
     * @return 角色分页列表
     */
    PageResult<CharacterVO> getCharacters(CharacterSearchDTO searchDTO);

    /**
     * 根据角色ID获取角色详情
     * 
     * @param characterId 角色ID
     * @return 角色详情
     */
    CharacterDetailVO getCharacterDetail(Long characterId);

    /**
     * 全文搜索角色
     * 
     * @param searchDTO 搜索条件
     * @return 角色分页列表
     */
    PageResult<CharacterVO> searchCharacters(CharacterSearchDTO searchDTO);

    /**
     * 根据ID列表批量获取角色信息
     * 
     * @param characterIds 角色ID列表
     * @return 角色列表
     */
    List<CharacterVO> getCharactersByIds(List<Long> characterIds);

    /**
     * 根据角色ID获取角色信息（内部接口）
     * 
     * @param characterId 角色ID
     * @return 角色详情
     */
    CharacterDetailVO getCharacterById(Long characterId);

    /**
     * 初始化预设角色库
     * 
     * @return 初始化结果
     */
    PresetInitResult initPresetCharacters();

    /**
     * 获取热门角色
     * 
     * @param limit 限制数量
     * @return 角色列表
     */
    List<CharacterVO> getPopularCharacters(Integer limit);

    /**
     * 根据技能类型获取角色
     * 
     * @param skillType 技能类型
     * @param limit 限制数量
     * @return 角色列表
     */
    List<CharacterVO> getCharactersBySkillType(String skillType, Integer limit);

    /**
     * 创建角色
     * 
     * @param createDTO 角色创建请求
     * @return 创建的角色信息
     */
    CharacterVO createCharacter(CharacterCreateDTO createDTO);

    /**
     * 更新角色
     * 
     * @param updateDTO 角色更新请求
     * @return 更新后的角色信息
     */
    CharacterVO updateCharacter(CharacterUpdateDTO updateDTO);

    /**
     * 删除角色
     * 
     * @param characterId 角色ID
     * @return 是否删除成功
     */
    Boolean deleteCharacter(Long characterId);

    /**
     * 批量删除角色
     * 
     * @param characterIds 角色ID列表
     * @return 删除成功的数量
     */
    Integer batchDeleteCharacters(List<Long> characterIds);

    /**
     * 启用/禁用角色
     * 
     * @param characterId 角色ID
     * @param status 状态
     * @return 是否操作成功
     */
    Boolean updateCharacterStatus(Long characterId, Integer status);
}
